<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
    <title id="bv20941">CREATE FOREIGN DATA WRAPPER</title>
    <body>
        <p id="sql_command_desc">Defines a new foreign-data wrapper.</p>
        <section id="section2">
            <title>Synopsis</title>
            <codeblock id="sql_command_synopsis">CREATE FOREIGN DATA WRAPPER <varname>name</varname>
    [ HANDLER <varname>handler_function</varname> | NO HANDLER ]
    [ VALIDATOR <varname>validator_function</varname> | NO VALIDATOR ]
    [ OPTIONS ( [ mpp_execute { 'master' | 'any' | 'all segments' } [, ] ] <varname>option</varname> '<varname>value</varname>' [, ... ] ) ]</codeblock>
        </section>
        <section id="section3">
            <title>Description</title>
            <p><codeph>CREATE FOREIGN DATA WRAPPER</codeph> creates a new foreign-data wrapper
                in the current database.  The user who defines the foreign-data wrapper becomes
                 its owner.</p>
            <p>Only superusers can create foreign-data wrappers.</p>
        </section>
        <section id="section4">
            <title>Parameters</title>
            <parml>
                <plentry>
                    <pt><varname>name</varname></pt>
                    <pd>
                        <p>The name of the foreign-data wrapper to create. The <varname>name</varname>
                           must be unique within the database.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>HANDLER <varname>handler_function</varname></pt>
                    <pd>
                        <p>The name of a previously registered function that Greenplum Database calls to retrieve the execution functions for foreign tables.  <varname>hander_function</varname> must take no arguments, and its return type must be <codeph>fdw_handler</codeph>.</p><p>It is possible to create a foreign-data wrapper with no handler function, but you can only declare, not access, foreign tables using such a wrapper.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>VALIDATOR <varname>validator_function</varname></pt>
                    <pd>
                        <p>The name of a previously registered function that Greenplum Database calls to check the options provided to the foreign-data wrapper. This function also checks the options for foreign servers, user mappings, and foreign tables that use the foreign-data wrapper. If no validator function or <codeph>NO VALIDATOR</codeph> is specified, Greenplum Database does not check options at creation time. (Depending upon the implementation, foreign-data wrappers may ignore or reject invalid options at runtime.)</p><p><varname>validator_function</varname> must take two arguments: one of type <codeph>text[]</codeph>, which contains the array of options as stored in the system catalogs, and one of type <codeph>oid</codeph>, which identifies the OID of the system catalog containing the options.</p><p>The return type is ignored; <varname>validator_function</varname> should report invalid options using the <codeph>ereport(ERROR)</codeph> function.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>OPTIONS ( <varname>option</varname> '<varname>value</varname>' [, ... ] )</pt>
                    <pd>
                        <p>The options for the new foreign-data wrapper. Option names must be unique. The option names and values are foreign-data wrapper-specific and are validated using the foreign-data wrappers' <varname>validator_function</varname>.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>mpp_execute { 'master' | 'any' | 'all segments' }</pt>
                    <pd>
                        <p>An option that identifies the host from which the foreign-data wrapper
                            reads or writes data: <ul id="ul_zcg_2vd_mgb">
                                <li><codeph>master</codeph> (the default)—Read or write data from the
                                    master host.</li>
                                <li><codeph>any</codeph>—Read data from either the master host or
                                    any one segment, depending on which path costs less.</li>
                                <li><codeph>all segments</codeph>—Read or write data from all segments. To
                                    support this option value, the foreign-data wrapper must have a
                                    policy that matches the segments to data.
                                  <note>Greenplum Database supports parallel writes to foreign tables
                                   only when you set <codeph>mpp_execute 'all segments'</codeph>.</note></li>
                            </ul></p>
                        <p>Support for the foreign-data wrapper <codeph>mpp_execute</codeph> option,
                            and the specific modes, is foreign-data wrapper-specific.</p>
                        <p>The <codeph>mpp_execute</codeph> option can be specified in multiple
                            commands: <codeph>CREATE FOREIGN TABLE</codeph>, <codeph>CREATE
                                SERVER</codeph>, and <codeph>CREATE FOREIGN DATA WRAPPER</codeph>.
                            The foreign table setting takes precedence over the foreign server
                            setting, followed by the foreign-data wrapper setting.</p>
                    </pd>
                </plentry>
            </parml>
        </section>
        <section id="section5">
            <title>Notes</title>
            <p>The foreign-data wrapper functionality is still under development. Optimization of queries is primitive (and mostly left to the wrapper).</p>
        </section>
        <section id="section6">
            <title>Examples</title>
            <p>Create a useless foreign-data wrapper named <codeph>dummy</codeph>:</p><codeblock>CREATE FOREIGN DATA WRAPPER dummy;</codeblock>
            <p>Create a foreign-data wrapper named <codeph>file</codeph> with a handler function named <codeph>file_fdw_handler</codeph>:</p><codeblock>CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;</codeblock>
            <p>Create a foreign-data wrapper named <codeph>mywrapper</codeph> that includes an option:</p><codeblock>CREATE FOREIGN DATA WRAPPER mywrapper OPTIONS (debug 'true');</codeblock>
        </section>
        <section id="section7">
            <title>Compatibility</title>
            <p><codeph>CREATE FOREIGN DATA WRAPPER</codeph> conforms to ISO/IEC 9075-9 (SQL/MED), with the exception that the <codeph>HANDLER</codeph> and <codeph>VALIDATOR</codeph> clauses are extensions, and the standard clauses <codeph>LIBRARY</codeph> and <codeph>LANGUAGE</codeph> are not implemented in Greenplum Database.</p>
            <p>Note, however, that the SQL/MED functionality as a whole is not yet conforming.</p>
        </section>
        <section id="section8">
            <title>See Also</title>
            <p><codeph><xref href="ALTER_FOREIGN_DATA_WRAPPER.xml#topic1">ALTER FOREIGN DATA WRAPPER</xref></codeph>,
                        <codeph><xref href="DROP_FOREIGN_DATA_WRAPPER.xml#topic1">DROP
                    FOREIGN DATA WRAPPER</xref></codeph>,
                        <codeph><xref href="CREATE_SERVER.xml#topic1">CREATE
                    SERVER</xref></codeph>,
                        <codeph><xref href="CREATE_USER_MAPPING.xml#topic1">CREATE
                    USER MAPPING</xref></codeph></p>
        </section>
    </body>
</topic>
